---
title: 快速入门
---

## 概述

在本文档中，你将学习如何在一个React项目中使用AMLL核心组件。

快速入门文档仅包含使用AMLL的核心功能的教程。部分其他功能需要依赖bncm包。

> 目前，AMLL仅提供了对core的React绑定，AMLL的其他组件并未包含在内，你可以在bncm中找到它们。未来，AMLL将提供包含AMLL播放页面其他组件的react-full。

## 准备工作

### 1.创建一个React项目

React项目可以使用多种方式创建。本文档将使用与[MDN React教程](https://developer.mozilla.org/zh-CN/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/React_getting_started)相同的create-react-app + jsx来作为示例。
你可以参考[MDN React教程](https://developer.mozilla.org/zh-CN/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/React_getting_started)创建一个React项目。并使用例如Visual Studio Code等开发软件打开你的项目。

### 2.使用包管理软件安装AMLL

安装AMLL使用的需要的依赖（如果以下列出的依赖包没有安装的话需要自行安装）：

```bash
npm install @pixi/app @pixi/core @pixi/display @pixi/filter-blur @pixi/filter-bulge-pinch @pixi/filter-color-matrix @pixi/sprite jss jss-preset-default # 使用 npm
yarn add @pixi/app @pixi/core @pixi/display @pixi/filter-blur @pixi/filter-bulge-pinch @pixi/filter-color-matrix @pixi/sprite jss jss-preset-default # 使用 yarn
```

安装 React 绑定需要使用的依赖（如果以下列出的依赖包没有安装的话需要自行安装）：

```bash
npm install react react-dom # 使用 npm
yarn add react react-dom # 使用 yarn
```

安装本体框架：

```bash
npm install @applemusic-like-lyrics/react # 使用 npm
yarn add @applemusic-like-lyrics/react # 使用 yarn
```

现在，你已经具备在React中使用AMLL的必要条件

## 开始使用

### 1.在React项目中使用AMLL Lyric Player

Lyric Player是AMLL的核心组件之一，提供歌词的显示功能。

通过`import { LyricPlayer } from "@applemusic-like-lyrics/react";`你可以将AMLL的Lyric Player导入到你的React项目中。

随后AMLL Lyric Player的React组件`<LyricPlayer />`便可以使用。

下面是一段示例。

```jsx
import React from "react";
import { LyricPlayer } from "@applemusic-like-lyrics/react";

function App() {
  return (
	< LyricPlayer />
  );
}
export default App;
```

但是现在，AMLL Lyric Player还不会显示任何信息。你需要按照你的需要使用React的Props来为`<LyricPlayer />`赋值，同时根据歌曲的播放逐帧调用AMLL Lyric Player才能显示歌词。

现在，我们对代码稍做修改，使其满足我们的要求。

```jsx
import React,{ useState } from "react";
import { LyricPlayer } from "@applemusic-like-lyrics/react";
import { parseTTML } from '@applemusic-like-lyrics/core';

const [currentTime, setCurrentTime] = useState(0);
const [lyricLines, setLyricLines] = useState(0);
const audio = document.getElementById("amll-audio");//获取<audio>元素

const parsedResult = parseTTML(TTML-Lyrics-Text);//对歌词进行处理
setLyricLines(parsedResult);//利用useState设置歌词

let lastTime = -1;
const frame = (time) => {
    if (lastTime === -1) {
        lastTime = time;
    }
    if (!audio.paused) {
        const time = (audio.currentTime * 1000) | 0;
        setCurrentTime(time);
    }
    lastTime = time;
    requestAnimationFrame(frame);//逐帧调用
};
requestAnimationFrame(frame);

function App() {
    return (
	<>
	<audio id="amll-audio" src="Audio-Music-Src" controls />
        <LyricPlayer 
		lyricLines={lyricLines}  //设置歌词
		currentTime={currentTime}//通过逐帧调用函数，设置播放时间
	/>
	</>
    );
}
export default App;
```

现在，我们创建了一个`<audio>`元素，id为amll-audio，用以播放歌曲。使用React中的useState来设置AMLL Lyric Player的当前播放时间。 

定义一个frame函数，通过`requestAnimationFrame();`来逐帧调用。利用`setCurrentTime();`跟随音乐的播放来设置AMLL Lyric Player的时间，从而使AMLL Lyric Player进行歌词的演出。 

我们还差最后一步：lyricLines的设置。lyricLines需要处理好的TTML歌词。AMLL提供了TTML歌词的处理程序，即`parseTTML`。我们需要通过`import { parseTTML } from '@applemusic-like-lyrics/core';`来导入。利用`parseTTML();`处理歌词，并将处理好的歌词通过setLyricLines赋值给AMLL Lyric Player。

> 注意：目前main分支的AMLL无法使用此方法导入parseTTML，你需要从dev分支下packages/core/src/lyric/ttml.ts导入。

> 标准的使用方法应为从@applemusic-like-lyrics/ttml导入而不是/core。

### 2.在React项目中使用BackgroundRender

BackgroundRender是AMLL的另一个核心组件。提供了歌曲播放背景显示的功能。

> 在本教程中，为了简洁易懂，将以BackgroundRender中的EplorRenderer（真流体背景）作为示例。

> 在最新的dev分支中，EplorRenderer也为默认的BackgroundRender

我们需要通过
```jsx
import { BackgroundRender } from "@applemusic-like-lyrics/react";
import { EplorRenderer } from '@applemusic-like-lyrics/core';
```
来导入BackgroundRender与EplorRenderer。

我们将第三部分中的代码作为示例进行修改。

```jsx
import React,{ useState } from "react";
import { LyricPlayer, BackgroundRender } from "@applemusic-like-lyrics/react";
import { EplorRenderer } from '@applemusic-like-lyrics/core';
import { parseTTML } from '@applemusic-like-lyrics/core';

const [currentTime, setCurrentTime] = useState(0);
const [lyricLines, setLyricLines] = useState(0);
const [albumUrl, setAlbumUrl] = useState(0);
const audio = document.getElementById("amll-audio");

const parsedResult = parseTTML(TTML-Lyrics-Text);
setLyricLines(parsedResult);

setAlbumUrl(Album-Pic-Url);//利用useState传入专辑图url

let lastTime = -1;
const frame = (time) => {
    if (lastTime === -1) {
        lastTime = time;
    }
    if (!audio.paused) {
        const time = (audio.currentTime * 1000) | 0;
        setCurrentTime(time);
    }
    lastTime = time;
    requestAnimationFrame(frame);
};
requestAnimationFrame(frame);

function App() {
    return (
	<>
    <audio id="amll-audio" src="Audio-Music-Src" controls />
    <BackgroundRender
        albumImageUrl={albumUrl} //将歌曲封面图url传入，来生成动态背景
        renderer={EplorRenderer} //渲染器的选择，这里为EplorRenderer真流体
    />
    <LyricPlayer 
        lyricLines={lyricLines} 
        currentTime={currentTime} 
    />
	</>
    );
}
export default App;
```

通过使用`<BackgroundRender />`组件，并使用其Props进行设置，我们可以得到动态背景。

将专辑图的url传入`albumImageUrl`，并选择`EplorRenderer`为`renderer`，渲染器会自动处理图片，生成精美的动态背景。

## 结语

我们在本章中学习了如何快速入门AMLL。希望能帮助你更轻松地进行AMLL相关的开发。
